home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Almathera Ten Pack 2: CDPD 1
/
Almathera Ten on Ten - Disc 2: CDPD 1.iso
/
pd
/
276-300
/
299
/
rxil
/
functions.doc
< prev
next >
Wrap
Text File
|
1995-03-14
|
22KB
|
1,032 lines
ARexx Interface Library (Rxil) Function Documentation
Release X1.0
Copyright © 1989 by Donald T. Meyer, Stormgate Software
All Rights Reserved
The following is an alphabetical listing of the function documentation
which has been extracted from the .c source files.
----------------------------------------------------------------------
NAME
RxilCancel
SYNOPSIS
RxilCancel();
FUNCTION
Sets the abort condition for ARexx macros. This is accomplished
by setting the Abort flag in the RxilDef structure.
All ARexx messages received at the ARexx ports while this flag
is set will be returned with an error code.
Unless the RXIL_NO_CLEAR_ABORT flag is set, the Abort flag will
be cleared automaticly when the last ARexx program launched by
this application has finished.
INPUTS
None
RESULT
None
SIDES
HISTORY
01-Aug-89 Creation.
BUGS
SEE ALSO
----------------------------------------------------------------------
NAME
RxilCheckCancel
SYNOPSIS
flag = RxilCheckCancel();
BOOL flag;
FUNCTION
Checks to see if the button on the cancel macro requester has
been clicked by the user or not.
This will return FALSE if the cancel requester is not posted.
INPUTS
None
RESULT
A boolean TRUE if the cancel requester has been clicked.
SIDES
HISTORY
01-Aug-89 Creation.
BUGS
SEE ALSO
RxilPostCancel(), RxilEndCancel()
----------------------------------------------------------------------
NAME
RxilCheckPort
SYNOPSIS
RxilCheckPort();
FUNCTION
Called by the client program's eventloop upon recieving a message
at one of the ports.
This handles the dispatching ( via RxilDispatch() ) of ARexx
commands, the launching of "looped back" macros, and receiving
the replys to macro invocation messages which we have sent to
Rexxmaster.
This is a "safe" call in that if the ARexx library was unopened
or the port opening failed, nothing will go boom!
INPUTS
None
RESULT
None
SIDES
HISTORY
01-Aug-89 Creation.
BUGS
SEE ALSO
RxilInit(), RxilDispatch()
----------------------------------------------------------------------
NAME
RxilCheckResult
SYNOPSIS
RxilCheckResult( rexxmsg );
struct RexxMsg *rexxmsg;
FUNCTION
Verify that the secondary result field in a RexxMsg is
appropriatly set.
This should be called for a RexxMsg just prior to replying
it. This will deal with the case of a result string being
set when the calling program did not request it.
It will be freed, and an error code
set to indicate to the calling program that it should be
requesting a result for this command.
INPUTS
rexxmsg = pointer to the RexxMsg structure to be checked.
RESULT
None
SIDES
HISTORY
01-Aug-89 Creation.
BUGS
SEE ALSO
----------------------------------------------------------------------
NAME
RxilCleanup
SYNOPSIS
RxilCleanup( rdef )
struct RxilDef *rdef;
FUNCTION
Cleanup the entire ARexx port.
This will set the Abort flag, then wait till all ARexx program
invocations which we have made are completed.
At this time, all ARexx message ports will be closed.
Any remaining RxilInvocation structures which were allocated
via RxilCreateRxi() and not yet deleted via RxilDeleteRxi()
will be cleaned up and freed.
The ARexx library will be closed.
Finally, the RexxDef structure itself will be freed.
INPUTS
rdef = pointer to the RxilDef structure returned by a call to
RxilInit().
RESULT
None
SIDES
HISTORY
01-Aug-89 Creation.
BUGS
SEE ALSO
RxilInit(), RxilPending()
----------------------------------------------------------------------
NAME
RxilCleanupReturn
SYNOPSIS
RxilCleanupReturn( rxi );
struct RxilInvovcation *rxi;
FUNCTION
This will take a pointer to a RxilInvocation structure and
free what needs to be freed.
The RexxMsg pointer is then NULL'ed and the structure's state
set to AVAILABLE.
This should be called by the main program to cleanup after
a function or command has returned and after the main program
has done whatever it wanted to with the result.
This will close the extension filehandles for Stdin and Stdout.
INPUTS
rxi = pointer to the RxilInvocation structure to be cleaned up.
RESULT
None
SIDES
HISTORY
01-Aug-89 Creation.
BUGS
SEE ALSO
RxilCreateRxi(), RxilDeleteRxi(), RxilGetReturn()
----------------------------------------------------------------------
NAME
RxilCloseConsole
SYNOPSIS
RxilCloseConsole( rexxmsg )
struct RexxMsg *rexxmsg;
FUNCTION
This will close the AmigaDOS file handles contained in the
rm_Stdin and rm_Stdout fields of the RexxMsg. If the handles
are the same, only one close is performed.
This clears the fields. If the fields are NULL, then no action
is taken.
This function supports the rm_Stdin and rm_Stdout being seperate
handles, even though it's complimentary function,
RxilOpenConsole() does not do this.
INPUTS
rexxmsg = pointer to the RexxMsg whose IO streams are to be
closed.
RESULT
None
SIDES
HISTORY
01-Aug-89 Creation.
BUGS
SEE ALSO
RxilOpenConsole()
----------------------------------------------------------------------
NAME
RxilCmdLock
SYNOPSIS
RxilCmdLock( rexxmsg );
struct RexxMsg *rexxmsg;
FUNCTION
This is a "command" which would be called from the dispatch
function. This would handle the "LOCK" command that an ARexx
program could send to the application requesting access to
the private port.
INPUTS
rexxmsg A pointer to a RexxMsg structure.
RESULT
None
SIDES
HISTORY
01-Aug-89 Creation.
BUGS
SEE ALSO
RxilCmdUnlock()
----------------------------------------------------------------------
NAME
RxilCmdPending
SYNOPSIS
flag = RxilCmdPending();
FUNCTION
If any ARexx commands have been launched via
a call to RxilLaunch(), and have not yet terminated, this will
return TRUE.
INPUTS
None
RESULT
A boolean flag which indicates if any launches are in progress.
SIDES
HISTORY
01-Aug-89 Creation.
BUGS
SEE ALSO
RxilLaunch(), RxilPending(), RxilFuncPending()
----------------------------------------------------------------------
NAME
RxilCmdUnlock
SYNOPSIS
RxilCmdUnlock( rexxmsg );
struct RexxMsg *rexxmsg;
FUNCTION
This is a "command" which would be called from the dispatch
function. This would handle the "UNLOCK" command that an
ARexx program could send to the application requesting
access to the private port.
Note: The privilege level for this command should be "secret",
since anyone who locked us will be able to meet that level,
and those who have not locked us can't slip the lock out
from under those who did (so to speak).
INPUTS
rexxmsg A pointer to a RexxMsg structure.
RESULT
None
SIDES
HISTORY
01-Aug-89 Creation.
BUGS
SEE ALSO
RxilCmdLock()
----------------------------------------------------------------------
NAME
RxilCreateRxi
SYNOPSIS
rxi = RxilCreateRxi( name, type );
struct RxilInvocation *rxi;
char *name;
ULONG type;
FUNCTION
Allocate a RxilInvocation structure and initialize it to
the defaults which are contained in the global RxilDef
structure.
INPUTS
name = character string containing the name of the ARexx
program that will be launched with the structure.
type = determines wether this will be used to launch commands
or functions. Must be set to either RXCOMM or RXFUNC.
RESULT
A pointer to a newly allocated and initialized RxilInvocation
structure, or NULL if one could not be allocated.
SIDES
HISTORY
01-Aug-89 Creation.
BUGS
SEE ALSO
RxilDeleteRxi()
----------------------------------------------------------------------
NAME
RxilDeletePort
SYNOPSIS
RxilDeletePort( port );
struct MsgPort *port;
FUNCTION
This will safely delete a message port used to receive commands
from ARexx.
This is acomplished by setting a failure return code and
replying the message if it is from ARexx.
If the message is not from ARexx, it is merely replied.
WARNING: If the port was/is used to receive replys, there must
be no chance of a reply being pending when this function is
called!
INPUTS
port = pointer to a MsgPort. Normally one that was opened
for receiving ARexx commands.
RESULT
None
SIDES
HISTORY
01-Aug-89 Creation.
BUGS
SEE ALSO
----------------------------------------------------------------------
NAME
RxilDeleteRxi
SYNOPSIS
RxilDeleteRxi( rxi );
struct RxilInvocation *rxi;
FUNCTION
Remove the structure allocated by a call to RxilCreateRxi() from
the linked list, and then frees it's memory.
INPUTS
rxi = a pointer to the RxilInvocation structure to delete.
This must have been allocated by a call to RxilCreateRxi().
RESULT
None
SIDES
HISTORY
01-Aug-89 Creation.
BUGS
SEE ALSO
RxilCreateRxi()
----------------------------------------------------------------------
NAME
RxilDispatch
SYNOPSIS
RxilDispatch( rexxmsg, cmd );
struct RexxMsg *rexxmsg;
char *cmd;
FUNCTION
This is really an "internal" function which is used by
the RxilCheckPort() function to dispatch commands.
It is not static, since it may be usefull by itself, or
it may desireable to replace it with a custom version
in some applications. This can be done simply by overriding
it, rather than editing the library itself.
This is NOT a "safe" call, since it should never be called
directly from client code.
It is however safe if the client fails to initialize the command
table pointer.
INPUTS
rexxmsg = pointer to the RexxMsg structure for the command we
are dispatching.
cmd = the command name string.
RESULT
None
SIDES
HISTORY
01-Aug-89 Creation.
26-Sep-89 Changed to use maximum and minimum argcounts.
BUGS
SEE ALSO
RxilCheckPort()
----------------------------------------------------------------------
NAME
RxilDumpRdef
SYNOPSIS
RxilDumpRdef( rdef, flags );
struct RxilDef *rdef;
ULONG flags;
FUNCTION
This function is for debug and testing purposes. It will
dump information about the current ARexx environment to the
CLI.
INPUTS
rdef = pointer to the global RxilDef structure.
flags = an unsigned long whose bits control just what information
about the RxilDef structure is displayed.
RESULT
None
SIDES
HISTORY
01-Aug-89 Creation.
25-Sep-89 Added display of library version string.
01-Oct-89 Added "flags" argument to control just what is
displayed, and ability to display the commands.
10-Nov-89 Changed format of command info display slightly.
BUGS
SEE ALSO
----------------------------------------------------------------------
NAME
RxilEndCancel
SYNOPSIS
RxilEndCancel();
FUNCTION
Removes the cancel requester.
INPUTS
None
RESULT
None
SIDES
HISTORY
01-Aug-89 Creation.
BUGS
SEE ALSO
RxilPostCancel(), RxilCheckCancel()
----------------------------------------------------------------------
NAME
RxilFuncPending
SYNOPSIS
flag = RxilFuncPending();
FUNCTION
If any ARexx functions have been launched via
a call to RxilLaunch(), and have not yet terminated, this will
return TRUE.
INPUTS
None
RESULT
A boolean flag which indicates if any launches are in progress.
SIDES
HISTORY
01-Aug-89 Creation.
BUGS
SEE ALSO
RxilLaunch(), RxilPending(), RxilCmdPending()
----------------------------------------------------------------------
NAME
RxilGetReturn
SYNOPSIS
rxi = RxilGetReturn();
struct RxilInvocation *rxi;
FUNCTION
This will return a pointer to any RxilInvocation message
that has been replyed (but not yet cleaned up and available).
NULL will be returned if all RxilInvocation structures which have
been allocated are available or pending.
INPUTS
None
RESULT
A pointer to a RxilInvocation structure. If none have been
replied and are available to be handled, this will return a NULL.
SIDES
HISTORY
01-Aug-89 Creation.
BUGS
SEE ALSO
----------------------------------------------------------------------
NAME
RxilHandleReturn
SYNOPSIS
RxilHandleReturn( rxi );
struct RxilInvocation *rxi;
FUNCTION
Take appropriate action (i.e., notify user) for the return
from an ARexx macro program.
The method of notification will be an Intuition Autorequester
if the Intuition library has been opened.
If it is not, the message will be sent to the CLI (if possible)
by opening "*". If this fails, no action is taken.
Output is via AmigaDOS functions such as Write(), as opposed
to using 'C' standard I/O such as printf().
INPUTS
rxi = pointer to a RxilInvocation structure that has been
replyed by the RexxMaster.
RESULT
None
SIDES
HISTORY
01-Aug-89 Creation.
10-Nov-89 Added Autorequester feature.
Changed to use AmigaDOS I/O rather than 'C' stdio.
BUGS
SEE ALSO
----------------------------------------------------------------------
NAME
RxilInit
SYNOPSIS
rdef = RxilInit( flags, portname );
struct RxilDef *rdef;
ULONG flags;
char *portname;
FUNCTION
Open the ARexx library and setup our message ports. Then
allocate a RxilDef structure and do some default initialization
of it.
The portname will have a unique "instance" number appended
to it in the format "<name>_#<n>" where <name> is the string as
specified in the portname argument, and <n> is a decimal number
from 1-99 inclusive. This feature may be inhibited by setting
the RXIL_AS_IS flag.
Even though this may fail, that should probably not be fatal
since the ARexx functionality is optional. The RxilCheckPort()
function is smart enough to just return if the rexx initialization
was not successsfull. Not to mention that RxilCheckPort() should
never get called since the rexx_sig_bit mask should be zero.
INPUTS
flags These are various defined constants which control
which ports get opened and other various aspects
of port initialization.
portname This is the name to use for the public ARexx port
that commands will be received at. It is suggested
that this be in uppercase and contain no spaces.
Maximum length is 40 characters, as set by the
defined constant RXIL_MAX_PORTNAME_LEN.
See discussion above about instance numbers.
RESULT
A pointer to a RxilDef structure. Return is NULL for failure
to initialize the ARexx ports.
SIDES
HISTORY
01-Aug-89 Creation.
23-Sep-89 Changed "flags" arg from int to ULONG
26-Sep-89 Sets the (new) version string pointer.
01-Oct-89 Changed PublicPort name storage from a pointer to
a character array. Added "instance" numbering.
Added check on portname length.
BUGS
This should probably share one signal bit between both ports
to avoid "hogging" signal bits.
SEE ALSO
RxilCleanup(), RXIL_AS_IS, RXIL_MAX_PORTNAME_LEN
----------------------------------------------------------------------
NAME
RxilLaunch
SYNOPSIS
result = RxilLaunch( rxi )
LONG result;
struct RxilInvocation *rxi;
FUNCTION
Launch an ARexx program by sending an invocation message
to the RexxMaster process. The RxilInvocation structure
which is allocated prior to this call via RxilCreateRxi()
contains the information neccessary to launch the program.
INPUTS
rxi A pointer to an initialized RxilInvocation structure.
RESULT
Zero if the launch was successful, non-zero otherwise.
SIDES
HISTORY
01-Aug-89 Creation.
BUGS
SEE ALSO
RxilCreateRxi(), RxilDeleteRxi()
----------------------------------------------------------------------
NAME
RxilOpenConsole
SYNOPSIS
RxilOpenConsole( console, rexxmsg );
char *console;
struct RexxMsg *rexxmsg;
FUNCTION
This will open an AmigaDOS stream as specified by the console
string. The filehandle is then placed in the rm_Stdin and
rm_Stdout fields of the RexxMsg.
INPUTS
console = a string which defines the console stream to be opened.
This will normally be something like "CON:0/0/400/100/".
rexxmsg = pointer to the RexxMsg that the AmigaDOS file handles
are to be set into.
RESULT
None
SIDES
HISTORY
01-Aug-89 Creation.
BUGS
SEE ALSO
RxilCloseConsole()
----------------------------------------------------------------------
NAME
RxilPending
SYNOPSIS
flag = RxilPending();
FUNCTION
If any ARexx functions or commands have been launched via
a call to RxilLaunch(), and have not yet terminated, this will
return TRUE.
INPUTS
None
RESULT
A boolean flag which indicates if any launches are in progress.
SIDES
HISTORY
01-Aug-89 Creation.
BUGS
SEE ALSO
RxilLaunch(), RxilCmdPending(), RxilFuncPending()
----------------------------------------------------------------------
NAME
RxilPostCancel
SYNOPSIS
RxilPostCancel();
FUNCTION
This will post a cancel requester to allow the user to halt
macro execution by clicking a button on the requester.
The CancelWindow member of the RxilDef structure controls
where the requester is posted.
In the current version, the cancel requester always opens it's
own window on the same screen as the Window whose pointer is
in CancelWindow. If CancelWindow is NULL, the window will open
on the WorkBench.
INPUTS
None
RESULT
None
SIDES
HISTORY
01-Aug-89 Creation.
BUGS
SEE ALSO
RxilCheckCancel(), RxilEndCancel()
----------------------------------------------------------------------
NAME
RxilSetResult
SYNOPSIS
RxilSetResult( rexxmsg, string );
struct RexxMsg *rexxmsg;
char *string;
FUNCTION
This can be called to handle the details of placing a result
string into the rexx message packet as the result Argstring.
If the string pointer is NULL, a general failure code will
be set.
This will deal with inability to allocate the Argstring by
setting a failure code in the RexxMsg.
INPUTS
rexxmsg = pointer to the RexxMsg that the reply is being set
into.
string = pointer to a null terminated text string which will
be converted to an Argstring and returned.
RESULT
SIDES
HISTORY
01-Aug-89 Creation.
BUGS
SEE ALSO
----------------------------------------------------------------------
NAME
RxilToRexx
SYNOPSIS
result = RxilToRexx( cmd, arg0, arg1, arg2, arg3 );
LONG result
ULONG cmd
STRPTR arg0
STRPTR arg1
STRPTR arg2
STRPTR arg3
FUNCTION
Send a command packet to the Rexx Master.
This is an asynchronous send, no success or failure will be
observed.
INPUTS
cmd = the command to send.
arg0 = a null-terminated string to convert into an Argstring.
arg1 = a null-terminated string to convert into an Argstring.
arg2 = a null-terminated string to convert into an Argstring.
arg3 = a null-terminated string to convert into an Argstring.
RESULT
Zero for success, non-zero to indicate failure.
SIDES
HISTORY
01-Aug-89 Creation.
BUGS
SEE ALSO
----------------------------------------------------------------------